docs: Inline GtkRecentManager documentation

diff --git a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml b/docs/reference/gtk/tmpl/gtkrecentmanager.sgml
deleted file mode 100644 (file)
index 0f5ab0a..0000000
--- a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml
+++ /dev/null
@@ -1,464 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkRecentManager
-
-<!-- ##### SECTION Short_Description ##### -->
-Managing Recently Used Files
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-#GtkRecentManager provides a facility for adding, removing and
-looking up recently used files.  Each recently used file is
-identified by its URI, and has meta-data associated to it, like
-the names and command lines of the applications that have
-registered it, the number of time each application has registered
-the same file, the mime type of the file and whether the file
-should be displayed only by the applications that have
-registered it.
-</para>
-
-<para>
-The #GtkRecentManager acts like a database of all the recently
-used files.  You can create new #GtkRecentManager objects, but
-it is more efficient to use the standard recent manager for
-the #GdkScreen so that informations about the recently used
-files is shared with other people using them.  In case the
-default screen is being used, adding a new recently used
-file is as simple as:
-</para>
-
-<informalexample>
-  <programlisting>
-GtkRecentManager *manager;
-
-manager = gtk_recent_manager_get_default ();
-gtk_recent_manager_add_item (manager, file_uri);
-  </programlisting>
-</informalexample>
-
-While looking up a recently used file is as simple as:
-
-<informalexample>
-  <programlisting>
-GtkRecentManager *manager;
-GtkRecentInfo *info;
-GError *error = NULL;
-
-manager = gtk_recent_manager_get_default ();
-info = gtk_recent_manager_lookup_item (manager, file_uri, &amp;error);
-if (error)
-  {
-    g_warning ("Could not find the file: &percnt;s", error-&gt;message);
-    g_error_free (error);
-  }
-else
-  {
-    /* Use the info object */
-    gtk_recent_info_unref (info);
-  }
-  </programlisting>
-</informalexample>
-
-<para>
-Recently used files are supported since GTK+ 2.10.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkRecentManager ##### -->
-<para>
-Acts as a database of information about the list of recently
-used files.  Normally, you retrieve the recent manager for a
-particular screen using gtk_recent_manager_get_for_screen()
-and it will contain information about current recent manager
-for that screen.</para>
-
-
-<!-- ##### SIGNAL GtkRecentManager::changed ##### -->
-<para>
-
-</para>
-
-@recentmanager: the object which received the signal.
-
-<!-- ##### ARG GtkRecentManager:filename ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkRecentManager:limit ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkRecentManager:size ##### -->
-<para>
-
-</para>
-
-<!-- ##### STRUCT GtkRecentInfo ##### -->
-<para>
-Contains informations found when looking up an entry of the
-recently used files list.
-</para>
-
-
-<!-- ##### STRUCT GtkRecentData ##### -->
-<para>
-
-</para>
-
-@display_name: 
-@description: 
-@mime_type: 
-@app_name: 
-@app_exec: 
-@groups: 
-@is_private: 
-
-<!-- ##### MACRO GTK_RECENT_MANAGER_ERROR ##### -->
-<para>
-The #GQuark used for #GtkRecentManagerError errors.
-</para>
-
-
-
-<!-- ##### ENUM GtkRecentManagerError ##### -->
-<para>
-
-</para>
-
-@GTK_RECENT_MANAGER_ERROR_NOT_FOUND: 
-@GTK_RECENT_MANAGER_ERROR_INVALID_URI: 
-@GTK_RECENT_MANAGER_ERROR_INVALID_ENCODING: 
-@GTK_RECENT_MANAGER_ERROR_NOT_REGISTERED: 
-@GTK_RECENT_MANAGER_ERROR_READ: 
-@GTK_RECENT_MANAGER_ERROR_WRITE: 
-@GTK_RECENT_MANAGER_ERROR_UNKNOWN: 
-
-<!-- ##### FUNCTION gtk_recent_manager_new ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_manager_get_default ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_manager_add_item ##### -->
-<para>
-
-</para>
-
-@manager: 
-@uri: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_manager_add_full ##### -->
-<para>
-
-</para>
-
-@manager: 
-@uri: 
-@recent_data: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_manager_remove_item ##### -->
-<para>
-
-</para>
-
-@manager: 
-@uri: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_manager_lookup_item ##### -->
-<para>
-
-</para>
-
-@manager: 
-@uri: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_manager_has_item ##### -->
-<para>
-
-</para>
-
-@manager: 
-@uri: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_manager_move_item ##### -->
-<para>
-
-</para>
-
-@manager: 
-@uri: 
-@new_uri: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_manager_get_items ##### -->
-<para>
-
-</para>
-
-@manager: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_manager_purge_items ##### -->
-<para>
-
-</para>
-
-@manager: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_ref ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_unref ##### -->
-<para>
-
-</para>
-
-@info: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_uri ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_display_name ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_description ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_mime_type ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_added ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_modified ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_visited ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_private_hint ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_application_info ##### -->
-<para>
-
-</para>
-
-@info: 
-@app_name: 
-@app_exec: 
-@count: 
-@time_: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_applications ##### -->
-<para>
-
-</para>
-
-@info: 
-@length: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_last_application ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_groups ##### -->
-<para>
-
-</para>
-
-@info: 
-@length: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_has_group ##### -->
-<para>
-
-</para>
-
-@info: 
-@group_name: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_has_application ##### -->
-<para>
-
-</para>
-
-@info: 
-@app_name: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_icon ##### -->
-<para>
-
-</para>
-
-@info: 
-@size: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_short_name ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_uri_display ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_get_age ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_is_local ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_exists ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_recent_info_match ##### -->
-<para>
-
-</para>
-
-@info_a: 
-@info_b: 
-@Returns: 
-
-

diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c
index 58b41dca79462a55cfc28eb0093a40b08f35d5d3..4226de2997e14fbe1af23edc9fc4adff69833698 100644 (file)
--- a/gtk/gtkrecentmanager.c
+++ b/gtk/gtkrecentmanager.c
@@ -18,6 +18,75 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  */
 
+/**
+ * SECTION:gtkrecentmanager
+ * @Title: GtkRecentManager
+ * @short_description: Managing recently used files
+ * @See_Also: #GBookmarkFile, #GtkSettings, #GtkRecentChooser
+ *
+ * #GtkRecentManager provides a facility for adding, removing and
+ * looking up recently used files. Each recently used file is
+ * identified by its URI, and has meta-data associated to it, like
+ * the names and command lines of the applications that have
+ * registered it, the number of time each application has registered
+ * the same file, the mime type of the file and whether the file
+ * should be displayed only by the applications that have
+ * registered it.
+ *
+ * <note><para>The recently used files list is per user.</para></note>
+ *
+ * The #GtkRecentManager acts like a database of all the recently
+ * used files. You can create new #GtkRecentManager objects, but
+ * it is more efficient to use the default manager created by GTK+.
+ *
+ * Adding a new recently used file is as simple as:
+ *
+ * |[
+ * GtkRecentManager *manager;
+ *
+ * manager = gtk_recent_manager_get_default ();
+ * gtk_recent_manager_add_item (manager, file_uri);
+ * ]|
+ *
+ * The #GtkRecentManager will try to gather all the needed information
+ * from the file itself through GIO.
+ *
+ * Looking up the meta-data associated with a recently used file
+ * given its URI requires calling gtk_recent_manager_lookup_item():
+ *
+ * |[
+ * GtkRecentManager *manager;
+ * GtkRecentInfo *info;
+ * GError *error = NULL;
+ *
+ * manager = gtk_recent_manager_get_default ();
+ * info = gtk_recent_manager_lookup_item (manager, file_uri, &amp;error);
+ * if (error)
+ *   {
+ *     g_warning ("Could not find the file: &percnt;s", error-&gt;message);
+ *     g_error_free (error);
+ *   }
+ * else
+ *  {
+ *    /&ast; Use the info object &ast;/
+ *    gtk_recent_info_unref (info);
+ *  }
+ * ]|
+ *
+ * In order to retrieve the list of recently used files, you can use
+ * gtk_recent_manager_get_items(), which returns a list of #GtkRecentInfo
+ * structures.
+ *
+ * A #GtkRecentManager is the model used to populate the contents of
+ * one, or more #GtkRecentChooser implementations.
+ *
+ * <note><para>The maximum age of the recently used files list is
+ * controllable through the #GtkSettings:gtk-recent-files-max-age
+ * property.</para></note>
+ *
+ * Recently used files are supported since GTK+ 2.10.
+ */
+
 #include "config.h"
 
 #include <sys/types.h>
@@ -59,6 +128,17 @@ typedef struct
   time_t stamp;
 } RecentAppInfo;
 
+/**
+ * GtkRecentInfo:
+ *
+ * <structname>GtkRecentInfo</structname> is an opaque data structure
+ * whose members can only be accessed using the provided API.
+ *
+ * <structname>GtkRecentInfo</structname> constains all the meta-data
+ * associated with an entry in the recently used files list.
+ *
+ * Since: 2.10
+ */
 struct _GtkRecentInfo
 {
   gchar *uri;
@@ -84,7 +164,6 @@ struct _GtkRecentInfo
   gint ref_count;
 };
 
-
 struct _GtkRecentManagerPrivate
 {
   gchar *filename;
@@ -235,7 +314,8 @@ gtk_recent_manager_class_init (GtkRecentManagerClass *klass)
    * @recent_manager: the recent manager
    *
    * Emitted when the current recently used resources manager changes its
-   * contents.
+   * contents, either by calling gtk_recent_manager_add_item() or by another
+   * application.
    *
    * Since: 2.10
    */

diff --git a/gtk/gtkrecentmanager.h b/gtk/gtkrecentmanager.h
index 105d0e2fe7aa764224e6d89c886ea22a95178955..f23b61e364fc8c7ce854dec78b4644ebc8583648 100644 (file)
--- a/gtk/gtkrecentmanager.h
+++ b/gtk/gtkrecentmanager.h
@@ -81,14 +81,29 @@ struct _GtkRecentData
   gboolean is_private;
 };
 
+/**
+ * GtkRecentManager:
+ *
+ * <structname>GtkRecentManager</structname> contains only private data
+ * and should be accessed using the provided API.
+ *
+ * Since: 2.10
+ */
 struct _GtkRecentManager
 {
+  /* <private> */
   GObject parent_instance;
 
-  /* <private> */
   GtkRecentManagerPrivate *priv;
 };
 
+/**
+ * GtkRecentManagerClass:
+ *
+ * <structname>GtkRecentManagerClass</structname> contains only private data.
+ *
+ * Since: 2.10
+ */
 struct _GtkRecentManagerClass
 {
   /*< private >*/
@@ -118,8 +133,10 @@ struct _GtkRecentManagerClass
  *   resources file.
  * @GTK_RECENT_MANAGER_ERROR_UNKNOWN: unspecified error.
  *
- * Error codes for GtkRecentManager operations
- **/
+ * Error codes for #GtkRecentManager operations
+ *
+ * Since: 2.10
+ */
 typedef enum
 {
   GTK_RECENT_MANAGER_ERROR_NOT_FOUND,
@@ -131,6 +148,13 @@ typedef enum
   GTK_RECENT_MANAGER_ERROR_UNKNOWN
 } GtkRecentManagerError;
 
+/**
+ * GTK_RECENT_MANAGER_ERROR:
+ *
+ * The #GError domain for #GtkRecentManager errors.
+ *
+ * Since: 2.10
+ */
 #define GTK_RECENT_MANAGER_ERROR       (gtk_recent_manager_error_quark ())
 GQuark         gtk_recent_manager_error_quark (void);